Skip to content

ProveKit docs for integration#435

Merged
Bisht13 merged 4 commits into
docs-stagingfrom
px/docs-e2e-rust-polish
May 12, 2026
Merged

ProveKit docs for integration#435
Bisht13 merged 4 commits into
docs-stagingfrom
px/docs-e2e-rust-polish

Conversation

@Bisht13
Copy link
Copy Markdown
Collaborator

@Bisht13 Bisht13 commented May 10, 2026

Summary

  • Reworked docs structure for setup, E2E flows, concepts, and reference.
  • Added Rust E2E, artifact lifecycle, security model, installation, and glossary pages.
  • Fixed visual alignment issues and tightened prose around verified APIs and artifact rules.

Validation

  • git diff --check
  • pnpm --dir docs check
  • pnpm --dir docs build
  • typos README.md docs/README.md docs/src/content/docs docs/astro.config.mjs

@Bisht13 Bisht13 changed the title Make docs precise enough for integration work Polish ProveKit docs for integration May 10, 2026
@Bisht13 Bisht13 changed the title Polish ProveKit docs for integration ProveKit docs for integration May 10, 2026
@Bisht13 Bisht13 force-pushed the px/docs-e2e-rust-polish branch from 7bef68c to be419eb Compare May 10, 2026 17:17
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 10, 2026

CSP benchmarks

Metric Value
Workflow status [PASS] success
Commit 4809a0ad9e3d
Run #25729638822
Circuits benchmarked 21
Iterations averaged per circuit 3

Prover time, peak RSS, peak heap, and verifier time are arithmetic means across the iterations. Peak heap comes from the largest peak memory entry in provekit-cli prove's tracing output; peak RSS is reported by /usr/bin/time -v (max-resident-set-size).

Each metric cell shows the current value followed by the percentage delta against the latest successful main run #25494153164. (new) marks circuits absent from the baseline.

Results
Circuit Constraints Witnesses Prover time Peak RSS Peak heap Verifier time Proof size PKP size
ecdsa_p256 143,282 (±0.0%) 258,158 (±0.0%) 2.98 s (-0.7%) 259 MB (±0.0%) 225 MB (±0.0%) 347 ms (-0.9%) 2.80 MB (-0.5%) 810 KB (±0.0%)
keccak_1024 822,870 (±0.0%) 1,543,366 (±0.0%) 6.37 s (-1.0%) 986 MB (±0.0%) 953 MB (±0.0%) 847 ms (-1.5%) 3.11 MB (-0.8%) 6.07 MB (±0.0%)
keccak_128 163,058 (±0.0%) 313,707 (±0.0%) 2.12 s (-0.9%) 276 MB (±0.0%) 242 MB (±0.0%) 377 ms (+1.8%) 2.79 MB (-0.9%) 1.22 MB (±0.0%)
keccak_2048 1,575,606 (±0.0%) 2,945,822 (±0.0%) 11.88 s (-0.5%) 1.81 GB (±0.0%) 1.80 GB (±0.0%) 1.44 s (-2.3%) 3.27 MB (+1.1%) 12.36 MB (±0.0%)
keccak_256 256,206 (±0.0%) 487,012 (±0.0%) 2.31 s (-1.0%) 328 MB (±0.0%) 291 MB (±0.0%) 410 ms (-1.6%) 2.82 MB (-1.2%) 1.97 MB (±0.0%)
keccak_512 445,094 (±0.0%) 839,130 (±0.0%) 3.65 s (-0.5%) 599 MB (+0.8%) 509 MB (±0.0%) 553 ms (-1.2%) 3.00 MB (-0.9%) 3.40 MB (±0.0%)
poseidon2_12 479 (±0.0%) 563 (±0.0%) 350 ms (-1.9%) 24.55 MB (+1.1%) 14.69 MB (±0.0%) 100 ms (±0.0%) 1.01 MB (-1.2%) 436 KB (±0.0%)
poseidon2_16 556 (±0.0%) 719 (±0.0%) 353 ms (-1.9%) 24.68 MB (+0.2%) 14.88 MB (±0.0%) 100 ms (-3.2%) 1.04 MB (+1.6%) 530 KB (±0.0%)
poseidon2_2 231 (±0.0%) 278 (±0.0%) 350 ms (±0.0%) 23.67 MB (+0.4%) 14.11 MB (±0.0%) 100 ms (-3.2%) 1.02 MB (-1.8%) 108 KB (±0.0%)
poseidon2_4 529 (±0.0%) 535 (±0.0%) 340 ms (-1.9%) 23.69 MB (-0.7%) 14.31 MB (±0.0%) 100 ms (±0.0%) 1.04 MB (+2.7%) 31.67 KB (±0.0%)
poseidon2_8 363 (±0.0%) 423 (±0.0%) 350 ms (-1.9%) 24.62 MB (+0.5%) 14.50 MB (±0.0%) 100 ms (±0.0%) 1.03 MB (-0.6%) 365 KB (±0.0%)
poseidon_12 504 (±0.0%) 524 (±0.0%) 353 ms (-1.0%) 24.69 MB (-0.2%) 14.69 MB (±0.0%) 100 ms (-3.2%) 1.03 MB (-0.2%) 410 KB (±0.0%)
poseidon_16 609 (±0.0%) 633 (±0.0%) 360 ms (+1.9%) 24.59 MB (±0.0%) 14.97 MB (±0.0%) 103 ms (+3.3%) 1.03 MB (-0.8%) 536 KB (±0.0%)
poseidon_2 240 (±0.0%) 249 (±0.0%) 343 ms (±0.0%) 23.45 MB (+0.2%) 14.02 MB (±0.0%) 100 ms (±0.0%) 1.04 MB (-0.6%) 53.79 KB (±0.0%)
poseidon_4 297 (±0.0%) 309 (±0.0%) 347 ms (-1.9%) 23.93 MB (±0.0%) 14.31 MB (±0.0%) 100 ms (±0.0%) 1.02 MB (-0.2%) 210 KB (±0.0%)
poseidon_8 402 (±0.0%) 418 (±0.0%) 350 ms (±0.0%) 23.87 MB (-0.3%) 14.50 MB (±0.0%) 100 ms (±0.0%) 1.05 MB (+1.1%) 305 KB (±0.0%)
sha256_1024 196,940 (±0.0%) 339,764 (±0.0%) 2.21 s (-1.3%) 311 MB (+1.1%) 273 MB (+0.1%) 420 ms (-0.8%) 2.80 MB (-1.3%) 1.89 MB (-0.6%)
sha256_128 46,398 (±0.0%) 80,974 (±0.0%) 1.09 s (±0.0%) 99.96 MB (-0.1%) 83.73 MB (+0.1%) 260 ms (±0.0%) 2.50 MB (-0.3%) 508 KB (-0.4%)
sha256_2048 345,399 (±0.0%) 612,724 (±0.0%) 3.58 s (-0.9%) 548 MB (±0.0%) 483 MB (-0.1%) 603 ms (-1.1%) 2.97 MB (-0.7%) 3.00 MB (-1.1%)
sha256_256 67,904 (±0.0%) 117,944 (±0.0%) 1.38 s (-1.7%) 150 MB (-1.5%) 131 MB (+0.7%) 290 ms (-1.1%) 2.65 MB (-0.7%) 721 KB (+0.2%)
sha256_512 110,916 (±0.0%) 191,884 (±0.0%) 1.50 s (-1.7%) 179 MB (-1.1%) 158 MB (±0.0%) 320 ms (-2.1%) 2.67 MB (-0.8%) 1.14 MB (+5.0%)

The docs now use a task-oriented structure with clearer setup, end-to-end flows, artifact lifecycle guidance, security notes, and reference pages. The Rust example uses published crates.io packages, SDK examples are tied to verified APIs, and custom visual components align correctly in dark and light themes.

Constraint: PR history must use professional commit messages without internal orchestration references.
Constraint: Rust dependencies must use published ProveKit crates instead of local path dependencies.
Rejected: Preserve intermediate checkpoint commits | they exposed internal coordination noise and made review harder.
Rejected: Keep Mermaid diagrams | local rendering was broken and CSS-native diagrams are easier to theme consistently.
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep docs examples tied to verified crate/API versions and rerun docs checks after visual CSS changes.
Tested: git diff --check
Tested: pnpm --dir docs check
Tested: pnpm --dir docs build
Tested: typos README.md docs/README.md docs/src/content/docs docs/astro.config.mjs
Not-tested: Hosted production deployment rendering
@Bisht13 Bisht13 force-pushed the px/docs-e2e-rust-polish branch from be419eb to 87171fc Compare May 10, 2026 17:29
Bisht13 added 3 commits May 11, 2026 19:37
- Reorganize sidebar (Start here, Build, Concepts, Reference, Operations)
- Add: What is ProveKit, Tutorial, Designing circuits, Performance,
  Comparison, FAQ, Examples catalog, FFI error codes, Starter templates,
  Changelog
- Rewrite landing with code-first hero and trimmed host integrations
- Add inline SVG architecture diagram and language tabs on integrations
- Verify all CLI flags, FFI codes, WASM bindings, Rust API and
  Poseidon2 hash arities against source; fix earlier fabrications
  (PK_OK -> PK_SUCCESS, hash_3 -> chained hash_2, server timeout defaults)
- Cross-link rustdoc and glossary anchors
- Strip em dashes throughout
Port the brand tokens, type stack, and component rules from the
Provekit Design System (README + colors_and_type.css) to the Starlight
docs site.

- Light is the canonical mode (brand is light-only); head script sets
  starlight-theme=light on first visit, toggle still works for users
  who switch
- Outfit (display/body) + Geist Mono (chrome) via Google Fonts;
  --sl-font / --sl-font-mono mapped so Starlight components inherit
- Brand palette: canvas #F8FEFF, surface #FFFFFF, ink #2D2D2B,
  brand #0D74FF, brand-ink #A2D0FC, lines #D1F5FF, mute #949494
- All chrome (sidebar group labels, table headers, TOC heading,
  pagination labels, asides titles, footer meta, hero CTAs) in
  Geist Mono ALL CAPS +0.02em tracking
- Square corners everywhere (cards, asides, code frames, buttons,
  dialogs); no box-shadows; borders define structure
- Asides re-skinned to brand palette (note=blue, tip=cyan,
  caution=bloom-orange, danger=bloom-pink) instead of Starlight defaults
- Code frames, search dialog, pagination, TOC, sidebar active page,
  hr / kbd / blockquote / mark, scrollbars all themed
- Selectors verified against rendered Starlight DOM; previous attempt
  targeted .sl-link-card (does not exist) and over-nested sidebar
  selectors that never matched
- v1.0.0 release wiring: install command, e2e Cargo.toml blocks,
  tutorial, starter template all pin "1.0.0"; landing banner,
  Changelog, FAQ, Project status acknowledge GitHub Releases as the
  authoritative version record
- Installation: surface cargo install provekit-cli alongside the
  source-checkout path via Starlight Tabs
- Quickstart: drop redundant prereqs, switch to plain provekit-cli
  commands with source-checkout substitution note, fix comma-splice in
  success Aside
- What is ProveKit: trim differentiator list to no-trusted-setup +
  post-quantum-secure base proof; drop When-to-use, When-not,
  You don't / You do need to know sections; replace with one "Before
  you build" pointer to the two concept pages
- Post-quantum security mentioned where it belongs: what-is,
  security-model (new Cryptographic assumptions section), FAQ (new Q),
  comparison matrix (two new rows for base + on-chain wrap)
- Swift platform scope narrowed to iOS only; macOS explicitly
  unsupported across landing, installation, swift e2e, starter-template
- Mavros removed from public docs (CLI flag still works, just not
  advertised); fixes 9 files
- Theme polish:
  - Double-line header bug fixed (scoped border to header.header)
  - Inline <code> in table cells stays on one line (no hyphen-wraps)
  - Sidebar/TOC inactive items use new --pk-ink-soft mid-tone (#5C5C5A)
    instead of pitch-black ink or unreadable mute grey
  - Asides reskinned to brand palette (note=blue, tip=cyan,
    caution=bloom-orange, danger=bloom-pink)
  - Pagination prev/next, code frame, search dialog, scrollbars, kbd,
    blockquote, hr all themed
  - Light-mode logo variant (logo-light.svg, ink #2D2D2B) replaces
    pale brand-ink on white backgrounds
@Bisht13 Bisht13 changed the base branch from main to docs-staging May 12, 2026 10:50
@Bisht13 Bisht13 merged commit 7647606 into docs-staging May 12, 2026
8 checks passed
@Bisht13 Bisht13 deleted the px/docs-e2e-rust-polish branch May 12, 2026 10:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant